3D Graphics Programming with QuickDraw 3D 1.5.4

Creating and Accessing Handle Storage Objects

QuickDraw 3D provides routines for creating and managing handle storage objects.

Q3HandleStorage_New

You can use the Q3HandleStorage_New function to create a new handle storage object.



 
TQ3StorageObject Q3HandleStorage_New (

                     Handle handle, 

                     unsigned long validSize);

handle: A handle to a buffer in memory, or NULL .
validSize: The size, in bytes, of the specified buffer.

DESCRIPTION

The Q3HandleStorage_New function returns, as its function result, a new handle storage object associated with the buffer specified by the handle and validSize parameters. Your application must not access that buffer until the associated storage object is closed or disposed of. If Q3HandleStorage_New cannot create a new storage object, it returns the value NULL . If you pass the value NULL in the handle parameter, QuickDraw 3D allocates a buffer of the specified size and later disposes of that buffer when the associated storage object is closed or disposed of.

ERRORS

kQ3ErrorOutOfMemory

Q3HandleStorage_Get

You can use the Q3HandleStorage_Get function to get information about a handle storage object.



 
TQ3Status Q3HandleStorage_Get (

                     TQ3StorageObject storage, 

                     Handle *handle, 

                     unsigned long *validSize);

storage: A handle storage object.
handle: On entry, a pointer to a handle. On exit, a pointer to a handle to the block of memory associated with the specified storage object.
validSize: On exit, the size, in bytes, of the block of memory whose address is returned through the buffer parameter.

DESCRIPTION

The Q3HandleStorage_Get function returns, in the handle and validSize parameters, the handle and size of the block of memory currently associated with the handle storage object specified by the storage parameter. Note that the returned handle is a handle to the storage object's data, not of a copy of that data.

ERRORS

kQ3ErrorInvalidObjectParameter kQ3ErrorNULLParameter

Q3HandleStorage_Set

You can use the Q3HandleStorage_Set function to set information about a handle storage object.



 
TQ3Status Q3HandleStorage_Set (

                     TQ3StorageObject storage, 

                     Handle handle, 

                     unsigned long validSize);

storage: A handle storage object.
handle: A handle to a contiguous block of memory to be associated with the specified storage object, or NULL .
validSize: The size, in bytes, of the specified buffer.

DESCRIPTION

The Q3HandleStorage_Set function sets the buffer location and size of the handle storage object specified by the storage parameter to the values specified in the handle and validSize parameters. If you pass the value NULL in the handle parameter, QuickDraw 3D allocates a buffer of the specified size and later disposes of that buffer when the associated storage object is closed or disposed of. If you pass NULL in handle and 0 in validSize , QuickDraw 3D allocates a buffer of a private default size.

SPECIAL CONSIDERATIONS

You must not use Q3HandleStorage_Set with an open handle storage object.

ERRORS

kQ3ErrorInvalidObjectParameter